---
title: Runtime
---

import AlphaCallout from '/snippets/alpha-lc-callout.mdx';

<AlphaCallout />

## Overview

:::python
LangChain's `create_agent` runs on LangGraph's runtime under the hood.
:::
:::js
LangChain's `createAgent` runs on LangGraph's runtime under the hood.
:::
LangGraph exposes a `Runtime` object with the following information:

1. Context: static information like user id, db connections, or other dependencies for an agent invocation
2. Store: a `BaseStore` instance used for long term memory
3. Stream writer: an object used for streaming information via the `"custom""` stream mode

You can access the runtime information within [tools](#inside-tools), [prompt](#inside-prompt), and [pre and post model hooks](#inside-pre-and-post-model-hooks).

## Access

:::python
When creating an agent with `create_agent`, you can specify a `context_schema` to define the structure of the `context` stored in the agent runtime.
:::
:::js
When creating an agent with `createAgent`, you can specify a `contextSchema` to define the structure of the `context` stored in the agent runtime.
:::

When invoking the agent, pass the `context` argument with the relevant configuration for the run:

:::python
```python
from dataclasses import dataclass

from langchain_core.messages import AnyMessage
from langchain.agents import create_agent
from langgraph.runtime import get_runtime

@dataclass
class Context:
    user_name: str

agent = create_agent(
    model="openai:gpt-5-nano",
    tools=[...],
    context_schema=Context  # [!code highlight]
)

agent.invoke(
    {"messages": [{"role": "user", "content": "What's my name?"}]},
    context=Context(user_name="John Smith")  # [!code highlight]
)
```
:::
:::js
```ts
import { z } from "zod";
import { createAgent } from "langchain";

const contextSchema = z.object({ // [!code highlight]
  userName: z.string(), // [!code highlight]
}); // [!code highlight]

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [
    /* ... */
  ],
  contextSchema, // [!code highlight]
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's my name?" }] },
  { context: { userName: "John Smith" } } // [!code highlight]
);
```
:::

### Inside tools

You can access the runtime information inside tools to:

* Access the context
* Read or write long term memory
* Write to the [custom stream](/oss/langchain/streaming#custom-updates) (ex, tool progress / updates)

:::python
Use the `get_runtime` function from `langgraph.runtime` to access the `Runtime` object inside a tool.

```python
from typing import Any

from langchain_core.tools import tool

@tool
def fetch_user_email_preferences() -> str:
    runtime = get_runtime(Context)
    user_id = runtime.context.user_id

    preferences: str = "The user prefers you to write a brief and polite email."
    if runtime.store:
        if memory := runtime.store.get(("users",), user_id):
            preferences = memory.value["preferences"]

    return preferences
```
:::
:::js
Use the `runtime` parameter to access the `Runtime` object inside a tool.

```ts
import { z } from "zod";
import { tool } from "langchain";
import { type Runtime } from "@langchain/langgraph";

const contextSchema = z.object({
  userName: z.string(),
});

const fetchUserEmailPreferences = tool(
  async (_, runtime: Runtime<z.infer<typeof contextSchema>>) => {
    const userName = runtime.context?.userName;
    if (!userName) {
      throw new Error("userName is required");
    }

    let preferences = "The user prefers you to write a brief and polite email.";
    if (runtime.store) {
      const memory = await runtime.store?.get(["users"], userName);
      if (memory) {
        preferences = memory.value.preferences;
      }
    }
    return preferences;
  },
  {
    name: "fetch_user_email_preferences",
    description: "Fetch the user's email preferences.",
    schema: z.object({}),
  }
);
```
:::

### Inside prompt

:::python
Use the `get_runtime` function from `langgraph.runtime` to access the `Runtime` object inside a prompt function.

```python
from dataclasses import dataclass

from langchain_core.messages import AnyMessage
from langchain.agents import create_agent
from langgraph.runtime import get_runtime

@dataclass
class Context:
    user_name: str

def my_prompt(state: State) -> list[AnyMessage]:
    runtime = get_runtime(Context)
    system_msg = (
        "You are a helpful assistant. "
        f"Address the user as {runtime.context.user_name}."
    )
    return [{"role": "system", "content": system_msg}] + state["messages"]

agent = create_agent(
    model="openai:gpt-5-nano",
    tools=[...],
    prompt=my_prompt,
    context_schema=Context
)

agent.invoke(
    {"messages": [{"role": "user", "content": "What's my name?"}]},
    context=Context(user_name="John Smith")
)
```
:::
:::js
Use the `runtime` parameter to access the `Runtime` object inside a prompt function.

```ts
import { z } from "zod";
import { createAgent, type AgentState, SystemMessage } from "langchain";
import { type Runtime } from "@langchain/langgraph";

const contextSchema = z.object({
  userName: z.string(),
});

const prompt = (
  state: AgentState,
  runtime: Runtime<z.infer<typeof contextSchema>>
) => {
  const userName = runtime.context?.userName;
  if (!userName) {
    throw new Error("userName is required");
  }

  const systemMsg = `You are a helpful assistant. Address the user as ${userName}.`;
  return [new SystemMessage(systemMsg), ...state.messages];
};

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [
    /* ... */
  ],
  prompt,
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's my name?" }] },
  { context: { userName: "John Smith" } }
);
```
:::

### Inside pre and post model hooks

:::python
To access the underlying graph runtime information in a pre or post model hook, you can:

1. Use the `get_runtime` function from `langgraph.runtime` to access the `Runtime` object inside the hook
2. Inject the `Runtime` directly via the hook signature

This above options are purely preferential and not functionally different.

<Tabs>
	<Tab title="Using get_runtime">
		```python
		from langgraph.runtime import get_runtime

		def pre_model_hook(state: State) -> State:
		    runtime = get_runtime(Context)
            ...
		```
	</Tab>
	<Tab title="Injection">
		```python
		from langgraph.runtime import Runtime

		def pre_model_hook(state: State, runtime: Runtime[Context]):
		    ...
		```
	</Tab>
</Tabs>
:::

:::js
Use the `runtime` parameter to access the `Runtime` object inside a pre or post model hook.

```ts
import { z } from "zod";
import { type Runtime } from "@langchain/langgraph";
import { createAgent, type AgentState } from "langchain";

const contextSchema = z.object({
  userName: z.string(),
});

const preModelHook = (
  state: AgentState,
  runtime: Runtime<z.infer<typeof contextSchema>>
) => {
  const userName = runtime.context?.userName;
  if (!userName) {
    throw new Error("userName is required");
  }

  return {
    // ...
  };
};

const postModelHook = (
  state: AgentState,
  runtime: Runtime<z.infer<typeof contextSchema>>
) => {
  const userName = runtime.context?.userName;
  if (!userName) {
    throw new Error("userName is required");
  }

  return {
    // ...
  };
};

const agent = createAgent({
  model: "openai:gpt-4o-mini",
  tools: [
    /* ... */
  ],
  contextSchema,
  preModelHook,
  postModelHook,
});
```
:::
